Authentication Manager - version 1.0.7 - February 14, 1994
by Robert John Churchill - rjc@umich.edu
Compiler: Symantec C version 6.0.1
Comments? Send mail to: authman-comments@ccs.itd.umich.edu
Problems? Send mail to: authman-problems@ccs.itd.umich.edu
To join the comments list? Send mail to: authman-comments-request@ccs.itd.umich.edu
To join the problems list? Send mail to: authman-problems-request@ccs.itd.umich.edu
NOTE: No warranty/guarantee is expressed or implied. Your mileage may vary. I'm providing this release so that those individuals with an interest in using Kerberos on the Mac will have a sampling of what is being done with Kerberos on the Mac here at the University of Michigan.
Export of this software from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.
PLEASE read this entire document. There are many specifics regarding getting Kerberos to work on the Macintosh.
Upgrading from an older version of AuthMan?
___________________________________
Remove the old version of AuthMan from your System Folder. Restart your Mac. Install the new version of AuthMan. Open AuthMan's control panel and configure with necessary information.
Current status of AuthMan at the University of Michigan - Feb '94
4) inSite (Oracle client app for hardware/software/networking/problem tracking) uses AuthMan
5) Various Mac clients such as Maelstrom (imap mail client) being modified to use AuthMan
6) UM is working with Apple, CMU and others to integrate kerberos into AOCE using AuthMan
(tentative info - the Kerberos in AOCE team at UM doesn't know what they are doing <sigh>)
7) MacZephyr implementation by CMU
Also, various universities in the US are using / developing for AuthMan. Names not mentioned to protect the innocent. Plans include modifying NewsWatcher, Eudora, NCSA Telnet, Fetch, Mandarin, etc.
Building Authentication Manager - (Full optimization recommended.)
1) Open "INIT Project" and build the code resource. This will merge "INIT 12" into the file "DRVR Project.rsrc". "INIT 12" loads in the ".AuthMan 1" driver at startup.
2) Open "DRVR Project" and build the driver. This will build a base "Authentication Manager" file containing all the resources from "DRVR Project.rsrc" as well as the ".AuthMan 1" driver (DRVR 12).
3) Open "cdev Project" and build the control panel interface code. This will merge "cdev -4064" into AuthMan.
4) Open "AUTH Project" and build the interface/MacTCP/kerberos/des code. This will merge "AUTH 1" and CCOD (dynamic loading code) into AuthMan. The DES code is from MIT's v4 implementation of Kerberos; to make the DES code work, the "AUTH Project" *M*U*S*T* be compiled with the "4-byte long" option in Think C so that an 'int' equals a 'long'.
5) Open "bootAuth Project" and build the (configurable) login-at-startup code. This will merge "INIT 128" into AuthMan. (Refer to note on INIT loading order.)
6) Open "bootTime Project" and build the (configurable) boot-time code. This will merge "INIT 129" into AuthMan. (Refer to note on INIT loading order.)
Configuring Authentication Manager
____________________________
Open AuthMan and add Kerberos realms and associated hosts. For example, the "UMICH.EDU" realm at the University of Michigan has three hosts: "fear.ifs.umich.edu", "surprise.ifs.umich.edu", and "ruthless.ifs.umich.edu".
Optionally, you may append a port number after the host name. For example, "fear.ifs.umich.edu 750". Originally, Kerberos used port 750. Newer implementations may use port 88. If unsure, a good guess is 750.
AuthMan supports both MIT Kerberos and Transarc AFS in terms of different StringToKey routines. AuthMan will now attempt both StringToKey methods unless "AFS" or "MIT" is appended to a realm name. For example, "UMICH.EDU AFS" indicates that the "UMICH.EDU" realm is AFS; only the appropriate AFS StringToKey would be used.
After adding all the realms and hosts, select the "local Kerberos realm" in the realm list and click the "Set Default Realm" button.
Click the Settings button to configure various settings regarding AuthMan.
AuthMan can be used to set the Mac's time, date, (potentially) time zone and daylight savings info. AuthMan supports BOOTP, TIME, and NTP. AuthMan only attempts to set the Mac's clock and associated info ONCE (at startup time). Various shareware NTP implementations exist for the Mac which run constantly. I recommend using one if you are able to; make sure whatever you use is "new" enough to support System 7 Pro's daylight savings bit.
If you are going to use BOOTP to set the Mac's date/time/time zone/daylight savings value, refer to the "BOOTP" section below. If you are going to be using NTP or TIME, refer to the "NTP/TIME" section below. It is worthwhile to read the "Setting Mac Info (general)" section no matter what method you are using to set the Mac's clock.
BOOTP section: (RFCs 1084 and 951).
____________________________________________
What is BOOTP:
BOOTP maps ethernet addresses to IP addresses as well as optionally provides information regarding various other IP services. It is "slightly" extensible; it has a 64 byte parameter area that can hold additional information.
The Mac's date and time have to be correct (within a five minute window of the time on the Kerberos servers). To convert to/from Unix time, the Mac's time zone and daylight savings setting are used.
BOOTP's "to", "ts" and T131 flags (T131 is an extended flag) are used to obtain this information at startup time (if the necessary BOOTP options are selected in AuthMan's control panel):
ts: IP address of a Unix machine running TIMED (most do)
to: set to "auto" (specifies # of seconds from GMT)
T128: "Macintosh Chooser Name"
T129: "Site name" (rather UM-specific)
T130: "Station number" (in hex) (rather UM-specific)
T131: "Daylight Savings Time Flag" (non-zero means dst in effect)
NTP section: (NTP RFCs 1361 and 1305; TIME RFC 868).
____________________________________________
What are NTP and TIME:
Both are time protocols. The TIME protocol returns Unix time. NTP (Network Time Protocol) is a much more versatile protocol than TIME. AuthMan implements NTP as described in the "Simple Network Time Protocol (SNTP)" RFC - basically, reducing the NTP time accuracy to that provided by the TIME protocol.
If you are using NTP or TIME, enter a list of servers the Mac should query. Note that NTP and TIME do not provide information regarding daylight savings. If the time appears to be set an hour off when using NTP or TIME, most likely your Mac has the wrong daylight savings setting - use System 7 Pro's "Date & Time" control panel to set it appropriately.
Setting Mac Info (general)
_______________________
The Mac's date and time have to be correct... there are many services to set this information.
Beginning with System 7 Pro, the "Date & Time" control panel has an option to turn on/off daylight savings. This setting, along with the "Time Zone" setting, must be set correctly. Make sure the Mac's date and time are correct.
If you are using an earlier version of the Mac OS, you will most likely not have a way to modify the daylight savings info (a bit setting stored in PRAM). You will need to use the "Map" control panel with a daylight savings offset calculated into the GMT offset. You will have to modify the value if/when you enter/leave daylight savings. For example, Michigan is -5 hours from GMT when not in daylight savings. However, when in daylight savings, the GMT offset would be "modified" to be -4 for Michigan instead. After entering in the correct GMT offset, set your Mac's date and time (use the "General Controls" control panel, the "Alarm Clock" DA, etc...)
Remember, if you are using System 7 Pro, use the "Date & Time" control panel instead of the "Map" control panel.
Building Sample Applications - (Full optimization recommended.)
I've included some crude sample applications that demonstrate using "authLibrary.c" which is the small glue file you would compile into any application you might write that you wanted to work with AuthMan.
1) AuthenticateNow pops up the authentication dialog box.
2) getUniqName gets the "name" the user last authenticated as. The "name" returned is whatever the user typed into the authentication dialog box; it might be qualified. Examples include "rjc" (which implies no instance and the default realm), "rjc@umich.edu", and "rjc.root@ccs.itd.umich.edu" (note the Kerberos "instance", specified by a period.)
3) testV2routines looks for a Kerberos ticket granting ticket (krbtgt) and optionally will prompt the user to authenticate. If a krbtgt is available, it will then request a service ticket. (Note: the service ticket is specific to the University of Michigan in this example and probably won't work anywhere else.) A list of all tickets will then be displayed followed by a list of all realms and the hosts in those realms.
4) expireTickets expires tickets held in AuthMan's ticket cache (located in the Mac's system heap.)
5) In the folder "AuthMan XCMD" you'll find (along with all the xcmd source) a sample stack which will use the XCMD to communicate with AuthMan.
6) In the folder "AuthMan DA" you'll find a desk accessory which lists all available tickets and allows ticket expiration.
AuthMan Resource Customization
__________________________
You might notice after using AuthMan a bit that it is somewhat "customized" for the University of Michigan. I've put virtually all interface details in resources that can be tailored using ResEdit. A list of resources you might want to change include:
(DLOG) DITL -4044 - the UM logo is 'PICT 128'; info at the bottom is PICT 129. The mention of "Campus Computing Sites" is a string that can be edited. Note dialog item #9, the small hot-rect re: the "Help/About" .
(ALRT) DITL -4042 - a message optionally displayed when users have problems
TEXT/styl 131 - "Help/About" text - if you don't want to provide help text, use ResEdit to remove the 'TEXT' and 'styl' ID 131 resources from AuthMan.
What do to if you want to use AuthMan on a 68000 Mac:
The amount of available stack space on a 68000 Mac is extremely low at times and System 28 errors (stack/heap collision) can occur. 68000 Macs by default only have 8K of stack while newer Macs have at least 24K. To compensate, I currently recommend increasing the amount of stack space in an application planning on calling Authman with the following routine:
void
increaseStackSize(long extraBytes)
{
SetApplLimit(GetApplLimit() - extraBytes);
}
Things Still To Do Include:
_____________________
1) need to have a call to add tickets from external callers; pretty simple
2) provide a routine to return a realm name given a host name
3) mk_priv: is there interest in this? mk_priv would allow for encrypted data sessions given a sessionKey
4) Detecting cmd-period isn't done 100% efficiently anywhere yet, and not 100% accurately in the control panel yet I believe
5) implement a subnet checking/comparison routine for the control panel option. I'd like this to work something like this: if the control panel contained "ccs.itd.umich.edu", a Mac who's domain name when resolved ended in that string would be allowed on if there was no response for any kerberos servers. Also, if the control panel contained "141.211" then if the Mac's IP address began with that string, it would be allowed in. Wildcard characters (*,?) are another option but probably not worth the time.
6) the cdev sends a message to the driver when the cdev is about to closed. The driver should reload and cache all the realms, hosts, and get IP addresses for everything at once. Currently it doesn't work that way - things are done on the fly which is much less efficient.
7) changing passwords: UDP (? maybe TCP) is used for MIT Kerberos, RX for AFS Kerberos
8) help balloons: frivalous but useful, especially when configuring the control panel
9) asynchronous cursor activity as well as <ESC> and cmd-period checking (already have the code - it merely needs to be integrated into the AuthMan package)
10) Integrate fast-DES code
11) Integrate code to allow other code modules such as INITs to be called after a user authenticates (I have a methodology where even INITs that load in before AuthMan can tell AuthMan to call a routine provided by the INIT... slick)
Changes made from release 1.0.5a5 (of Nov. 11, 1992) to release 1.0.7
1) when the "Protect" option is set in control panel, on close the 'cdev' -4064 resource (interface code) is now removed from AuthMan as well as having the filetype changed to 'INIT'.
2) bug fix: code which checked to see if a ticket expired was calling TickCount instead of GetDateTime (oops)
3) bug fix: needed to #include <Devices.h> in bootTime.c (was bootP.c)
4) bug fix: in drvr.c, wasn't getting actual vRefNum on which AuthMan resides - result was that apps using AuthMan would fail if on a different volume
5) bug fix(es): a few problems were noticed regarding byte-swapping. As far as I know, no one has yet verified that AuthMan will work with a little-endian Kerberos server. We're trying though, folks. Remember, this should only affect MIT Kerberos servers as AFS Kerberos servers are network-byte order at all times (we hope).
6) added support for directed-BOOTP packets (only broadcast-BOOTP was being used before) as well as support for TIMED (before, TIMED support was imbedded into BOOTP) as well as NTP support. Directed BOOTP packets may be useful for those who use static IP addresses but would like their Mac's clock/Map settings to always be correct; also, Macs on localtalk could use TIMED to at least set the time and date correctly... they'll still need to update the time zone and dst values when daylight savings changes.
7) when using BOOTP, now we try and get an ethernet address from .ENET as well as an IP address from MacTCP when forming the BOOTP packet
8) there is now an option to "lock" the name field when authenticating (potentially useful if you have your own private Mac; probably not very useful for a shared Mac)
9) a few cosmetic changes were made -- to the control panel settings dialog as well as the authentication dialog [ GetGray() is used if available for true grays ]
10) I've tossed together a sample XCMD for those individuals who are using Hypercard and would like to play around with AuthMan. The XCMD could do more... such as put an actual ticket into a container, I suppose. It you want to see more functionality in the XCMD, let me know.
11) Now, you can specify AFS or MIT after a realm name in AuthMan's control panel. If neither is specified, when authenticating both methods will be attempted (notice that the realm type will indicate UNKNOWN_REALM_TYPE when getting info on a realm). If either MIT or AFS is specified, only that method with be attempted. (The case of MIT or AFS is now insignificant)
12) NewPtrSys is now used to get various large blocks of temporary memory (such as tickets - which are approx. 1250 bytes). This may help with stack problems a bit.
13) The API was extending with a DES call to DES/unDES buffers.
14) AuthMan now registers itself with Gestalt. The response given back is AuthMan's version number (as indicated in the 'vers' resources) (different than the API version code returned with the openAuthMan call.) See the 'test V2 routines.c" file for how to break apart the version code response.
15) Displays more informative error msgs when authenticating (ID bad, PW bad, check time). It is a shame MIT and AFS kerberos handle "errors" differently (sigh).
16) System 7 Pro has defined a bit in the machineLocation structure as a "Daylight Savings" flag. This bit is set / reset via BOOTP code if T131 flag exists and is non-zero. Shame that System 7 Pro doesn't just do universal time, understand all time zones (not all of which are exactly one hour off, so I'm told) and general local time when a GetDateTime call is made. Unix does it right, why can't the Mac?
17) a few DLOGs and ALRTs were renumbered to take them out of the applications positive ID range
18) included a new DA to list/expire tickets - check it out. Password changing will be added into AuthMan's driver which the DA will use... expect it in the next release.
19) When the control panel closes it tries to send a control message to the driver telling it to reinitialize. If AuthMan isn't installed yet, the driver isn't available. Unfortunately, the Mac thinks the driver can be loaded as it is sitting in the current resource fork. That's a problem. The workaround was to set the current resource fork to that of the System file before trying to send a control message to AuthMan's driver. If AuthMan isn't installed, the Mac won't see the driver sitting in the control panel's resource fork so won't screw up.
Thanks to everyone who has looked at, worked with, and made changes to AuthMan so far.
